
/*
 * Copyright 2002-2012 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2012原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.parsing;

import org.springframework.beans.BeanMetadataElement;
import org.springframework.beans.factory.config.BeanDefinition;
import org.springframework.beans.factory.config.BeanReference;

/**
 * Interface that describes the logical view of a set of {@link BeanDefinition BeanDefinitions}
 * and {@link BeanReference BeanReferences} as presented in some configuration context.
 *
 * <p>With the introduction of {@link org.springframework.beans.factory.xml.NamespaceHandler pluggable custom XML tags},
 * it is now possible for a single logical configuration entity, in this case an XML tag, to
 * create multiple {@link BeanDefinition BeanDefinitions} and {@link BeanReference RuntimeBeanReferences}
 * in order to provide more succinct configuration and greater convenience to end users. As such, it can
 * no longer be assumed that each configuration entity (e.g. XML tag) maps to one {@link BeanDefinition}.
 * For tool vendors and other users who wish to present visualization or support for configuring Spring
 * applications it is important that there is some mechanism in place to tie the {@link BeanDefinition BeanDefinitions}
 * in the {@link org.springframework.beans.factory.BeanFactory} back to the configuration data in a way
 * that has concrete meaning to the end user. As such, {@link org.springframework.beans.factory.xml.NamespaceHandler}
 * implementations are able to publish events in the form of a {@code ComponentDefinition} for each
 * logical entity being configured. Third parties can then {@link ReaderEventListener subscribe to these events},
 * allowing for a user-centric view of the bean metadata.
 *
 * <p>Each {@code ComponentDefinition} has a {@link #getSource source object} which is configuration-specific.
 * In the case of XML-based configuration this is typically the {@link org.w3c.dom.Node} which contains the user
 * supplied configuration information. In addition to this, each {@link BeanDefinition} enclosed in a
 * {@code ComponentDefinition} has its own {@link BeanDefinition#getSource() source object} which may point
 * to a different, more specific, set of configuration data. Beyond this, individual pieces of bean metadata such
 * as the {@link org.springframework.beans.PropertyValue PropertyValues} may also have a source object giving an
 * even greater level of detail. Source object extraction is handled through the
 * {@link SourceExtractor} which can be customized as required.
 *
 * <p>Whilst direct access to important {@link BeanReference BeanReferences} is provided through
 * {@link #getBeanReferences}, tools may wish to inspect all {@link BeanDefinition BeanDefinitions} to gather
 * the full set of {@link BeanReference BeanReferences}. Implementations are required to provide
 * all {@link BeanReference BeanReferences} that are required to validate the configuration of the
 * overall logical entity as well as those required to provide full user visualization of the configuration.
 * It is expected that certain {@link BeanReference BeanReferences} will not be important to
 * validation or to the user view of the configuration and as such these may be omitted. A tool may wish to
 * display any additional {@link BeanReference BeanReferences} sourced through the supplied
 * {@link BeanDefinition BeanDefinitions} but this is not considered to be a typical case.
 *
 * <p>Tools can determine the importance of contained {@link BeanDefinition BeanDefinitions} by checking the
 * {@link BeanDefinition#getRole role identifier}. The role is essentially a hint to the tool as to how
 * important the configuration provider believes a {@link BeanDefinition} is to the end user. It is expected
 * that tools will <strong>not</strong> display all {@link BeanDefinition BeanDefinitions} for a given
 * {@code ComponentDefinition} choosing instead to filter based on the role. Tools may choose to make
 * this filtering user configurable. Particular notice should be given to the
 * {@link BeanDefinition#ROLE_INFRASTRUCTURE INFRASTRUCTURE role identifier}. {@link BeanDefinition BeanDefinitions}
 * classified with this role are completely unimportant to the end user and are required only for
 * internal implementation reasons.
 *
 * @author Rob Harrop
 * @author Juergen Hoeller
 * @since 2.0
 * @see AbstractComponentDefinition
 * @see CompositeComponentDefinition
 * @see BeanComponentDefinition
 * @see ReaderEventListener#componentRegistered(ComponentDefinition)
 */
/**
 *描述一组｛@link BeanDefinition BeanDefinitions｝的逻辑视图的接口
 *和{@linkBeanReferenceBeanReferences}，如某些配置上下文中所示。
 *
 *＜p＞随着{@link org.springframework.beans.factory.xml.NamespaceHandler可插入自定义xml标记}的引入，
 *现在，单个逻辑配置实体（在本例中为XML标记）可以
 *创建多个｛@link BeanDefinition BeanDefinitions｝和｛@linkBeanReference RuntimeBeanReference｝
 *以便为最终用户提供更简洁的配置和更大的便利。因此，它可以
 *不再假设每个配置实体（例如XML标记）映射到一个{@link BeanDefinition}。
 *对于工具供应商和其他希望呈现可视化或支持配置Spring的用户
 *应用程序，重要的是要有某种机制来绑定｛@link BeanDefinition BeanDefinitions｝
 *在{@linkorg.springframework.beans.factory.BeanFactory}中以某种方式返回到配置数据
 *这对最终用户具有具体意义。因此，｛@link.org.springframework.beans.factory.xml.NamespaceHandler｝
 *实现能够以｛@code ComponentDefinition｝的形式发布每个
 *正在配置逻辑实体。然后，第三方可以{@link ReaderEventListener订阅这些事件}，
 *允许以用户为中心的bean元数据视图。
 *
 *＜p＞每个｛@code ComponentDefinition｝都有一个｛@link#getSource源对象｝，它是特定于配置的。
 *在基于XML的配置中，这通常是包含用户的｛@linkorg.w3c.dom.Node｝
 *提供的配置信息。除此之外，每个｛@link BeanDefinition｝都包含在
 *｛@code ComponentDefinition｝有自己的｛@link BeanDefinition#getSource（）源对象｝，它可以指向
 *到另一组更具体的配置数据。除此之外，单个bean元数据片段
 *因为｛@link org.springframework.beans.PropertyValue PropertyValues｝也可能有一个源对象
 *甚至更高级别的细节。源对象提取通过
 *｛@link SourceExtractor｝，可根据需要进行自定义。
 *
 *＜p＞虽然通过以下方式提供了对重要｛@link BeanReference BeanReference｝的直接访问
 *｛@link#getBeanReferences｝，工具可能希望检查所有｛@link BeanDefinition BeanDefinitions｝以收集
 *完整的{@linkBeanReferenceBeanReferences}集。实施需要提供
 *验证
 *总体逻辑实体以及提供配置的完整用户可视化所需的实体。
 *预计某些｛@link BeanReference BeanReference｝对
 *验证或配置的用户视图，因此可以省略这些。工具可能希望
 *显示通过提供的
 *｛@link BeanDefinition BeanDefinitions｝，但这不是典型的情况。
 *
 *＜p＞工具可以通过检查
 *｛@link BeanDefinition#getRole角色标识符｝。该角色本质上是向工具提示如何
 *配置提供商认为{@link BeanDefinition}对最终用户很重要。这是预期的
 *工具将<strong>而不是</strong>显示给定对象的所有｛@link BeanDefinition BeanDefinition｝
 *｛@code ComponentDefinition｝选择根据角色进行筛选。工具可以选择制作
 *此过滤用户可配置。应特别通知
 *｛@link BeanDefinition#ROLE_INFRASTRUCTURE INFRASTRURE角色标识符｝。｛@link BeanDefinition BeanDefinitions｝
 *与此角色一起分类对最终用户来说是完全不重要的，只需要
 *内部实施原因。
 *
 *@作者Rob Harrop
 *@作者Juergen Hoeller
 *@自2.0起
 *@参见AbstractComponentDefinition
 *@参见CompositeComponentDefinition
 *@参见BeanComponentDefinition
 *@参见ReaderEventListener#componentRegistered（ComponentDefinition）
 */
public interface ComponentDefinition extends BeanMetadataElement {

	/**
	 * Get the user-visible name of this {@code ComponentDefinition}.
	 * <p>This should link back directly to the corresponding configuration data
	 * for this component in a given context.
	 */
	/**
	 *获取此｛@code ComponentDefinition｝的用户可见名称。
	 *＜p＞这应该直接链接回相应的配置数据
	 *对于给定上下文中的此组件。
	 */
	String getName();

	/**
	 * Return a friendly description of the described component.
	 * <p>Implementations are encouraged to return the same value from
	 * {@code toString()}.
	 */
	/**
	 *返回所描述组件的友好描述。
	 *＜p＞鼓励实现从
	 *｛@code toString（）｝。
	 */
	String getDescription();

	/**
	 * Return the {@link BeanDefinition BeanDefinitions} that were registered
	 * to form this {@code ComponentDefinition}.
	 * <p>It should be noted that a {@code ComponentDefinition} may well be related with
	 * other {@link BeanDefinition BeanDefinitions} via {@link BeanReference references},
	 * however these are <strong>not</strong> included as they may be not available immediately.
	 * Important {@link BeanReference BeanReferences} are available from {@link #getBeanReferences()}.
	 * @return the array of BeanDefinitions, or an empty array if none
	 */
	/**
	 *返回已注册的｛@link BeanDefinition BeanDefinitions｝
	 *以形成此｛@code ComponentDefinition｝。
	 *＜p＞应该注意，｛@code ComponentDefinition｝可能与
	 *通过{@link BeanReference引用}，
	 *然而，由于它们可能无法立即提供，因此<strong>不包括在内。
	 *重要的｛@link BeanReference BeanReference｝可从｛@link#getBeanReference（）｝获得。
	 *@返回BeanDefinitions数组，如果没有，则返回空数组
	 */
	BeanDefinition[] getBeanDefinitions();

	/**
	 * Return the {@link BeanDefinition BeanDefinitions} that represent all relevant
	 * inner beans within this component.
	 * <p>Other inner beans may exist within the associated {@link BeanDefinition BeanDefinitions},
	 * however these are not considered to be needed for validation or for user visualization.
	 * @return the array of BeanDefinitions, or an empty array if none
	 */
	/**
	 *返回表示所有相关的｛@link BeanDefinition BeanDefinitions｝
	 *此组件中的内部bean。
	 *＜p＞其他内部bean可能存在于关联的｛@link BeanDefinition BeanDefinitions｝内，
	 *然而，这些不被认为是验证或用户可视化所需的。
	 *@返回BeanDefinitions数组，如果没有，则返回空数组
	 */
	BeanDefinition[] getInnerBeanDefinitions();

	/**
	 * Return the set of {@link BeanReference BeanReferences} that are considered
	 * to be important to this {@code ComponentDefinition}.
	 * <p>Other {@link BeanReference BeanReferences} may exist within the associated
	 * {@link BeanDefinition BeanDefinitions}, however these are not considered
	 * to be needed for validation or for user visualization.
	 * @return the array of BeanReferences, or an empty array if none
	 */
	/**
	 *返回所考虑的｛@link BeanReference BeanReference｝集合
	 *对这个｛@code ComponentDefinition｝很重要。
	 *＜p＞关联的
	 *｛@link BeanDefinition BeanDefinitions｝，但这些不被考虑
	 *用于验证或用户可视化。
	 *@返回BeanReferences数组，如果没有，则返回空数组
	 */
	BeanReference[] getBeanReferences();

}
